ReaWild -- setup (Windows)
==================================


This turns bird call/song detections into coloured, labelled regions on a
REAPER timeline, so you can browse and confirm them by ear.

It uses BirdNET, which recognises around 6,500 species worldwide. It installs
BirdNET for you -- you don't need to find or set up anything yourself.

   PLEASE READ THIS BIT
   Windows support is brand new. It is expected to work, but you are the
   first person to run it on Windows, so if something looks wrong, it
   probably is -- it's the tool, not you. There's a "Send feedback" button
   at the bottom of the window; please use it rather than fighting with it.
   The window will also say, at the top, that it's on an unverified
   platform. That message disappears once it's confirmed working.


This copy is the one for Windows, 64-bit. If that isn't what you're on,
download the right one from https://www.soundingwild.com/labs/reawild --
the tool will also tell you itself, the first time you run it.


1. Install REAPER if you don't already have it, or UPDATE it to the newest
   version if you do (REAPER: Help -> Check for updates):
   https://www.reaper.fm/download.php
   ReaWild puts each model's regions on their own row ("lane"), which only
   recent REAPER can do -- it was tested with REAPER 7.79. On an older
   REAPER it still works, but every model's regions share one row.
   REAPER itself is free to try.
   Pick "Windows 64-bit".

2. Put this whole folder somewhere permanent, e.g. your Documents folder.
   Don't move it after this step -- the tool remembers where it lives and
   installs BirdNET right next to itself.

   Avoid OneDrive folders if you can. OneDrive likes to turn files into
   placeholders that aren't really on the disk, which confuses anything
   that reads them.

3. Open REAPER.
   - Go to the Actions menu -> Show action list...
   - Click "New action..." -> "Load ReaScript..."
   - Find this folder and pick "ReaWild v0.20.2.lua" -> Open -> Close.

4. With it selected in the Action list, click "Run".

5. First run: it will probably say it needs something called ReaImGui.
   Click "Yes" to install it automatically, then FULLY QUIT REAPER -- close
   every REAPER window, and check the taskbar. Just closing the project
   window is NOT enough; REAPER won't notice the new extension until it
   restarts. Reopen it, then repeat step 4.
   - If it still asks for ReaImGui after a genuine quit-and-reopen, it will
     offer to email Axel the report. Say yes -- that sends far more than a
     screenshot could. Nothing is sent until you press send in your own
     email app.

6. Sign in. The first window asks for your ReaWild account.
   - No account yet? Click "Create an account" (or go to
     https://www.soundingwild.com/labs/reawild and press "Ask for a
     licence"). Axel approves each account by hand and emails you
     when it's ready.
   - Once it's approved, type your email and password and click
     "Activate this computer". You need the internet for this once;
     after that ReaWild works offline.
   - One computer per account. To move to another computer, open
     the "Licence" panel at the bottom of the ReaWild window and press
     "Deactivate this computer" first, or remove the old one on your
     account page.

7. The window opens. If BirdNET isn't set up yet, that's the first thing it
   shows: click "Set up BirdNET automatically...". Before anything
   downloads it lists what it will install, how big each part is (about
   2.3 GB in all, plus up to 1 GB of temporary files) and how much free
   space your disk has, and asks whether there is room. Say yes and wait:
   it needs a real internet connection and a few minutes. You can keep
   using REAPER while it runs. Choosing Perch or BirdNET 3.0 later asks
   the same way before fetching their models.

   Everything it needs, including its own copy of Python, goes into this
   folder. Nothing is installed on the rest of the computer, so no
   administrator password or permission prompt is needed.

   There are three listening models: BirdNET 2.4 (the proven one),
   BirdNET 3.0 (a newer preview) and Perch v2. "Analyse" runs ALL of them,
   one after another, so you can compare them on the same recordings. The
   Model buttons at the top only choose whose settings you see and change.
   BirdNET 3.0 needs its own one-click setup first (pick it at the top:
   about 300 MB, plus a ~570 MB model on its first analysis); until then
   the others run without it. Perch and BirdNET 3.0 ask before fetching
   their models.

8. Once BirdNET is installed, the full window appears. In the "Site"
   section, give your recording site's coordinates: type them into
   "Latitude" and "Longitude" (decimal degrees, e.g. 45.68 and 13.77),
   paste them in any format into the box below, or click the map.
   South of the equator and west of Greenwich are NEGATIVE numbers --
   check the orange dot on the map is where you recorded.

   This is required, and it matters more than it looks: BirdNET builds its
   list of candidate species from where and when you recorded. Without it
   you get the full global list and a lot of nonsense.

   One REAPER project = one recording site. Start a new project for a
   different location rather than mixing them.

9. Add your audio files to the project, then press "Analyse". Each model
   runs in turn, and its regions appear as soon as it finishes. You can
   close the window meanwhile: open ReaWild again and it carries on.

   Every generated region name starts with "? ". That's deliberate: delete
   the "? " by hand once you've confirmed a bird by ear, and re-running the
   analysis will never overwrite or duplicate it.

10. Region lanes: each model's regions sit on their own lane in the ruler
   above the tracks, named after the model ("BirdNET 2.4", "BirdNET 3.0",
   "Perch v2"). To hide or show a lane, use the tick-boxes under "Region
   lanes" in ReaWild's window. Regions you made yourself are never hidden.

   Or put buttons on a REAPER toolbar: the "Toolbar actions" folder next
   to this file has one action per model plus one for all of them. Load
   them like step 3 (Actions -> Show action list -> New action... -> Load
   ReaScript...), then right-click a toolbar -> Customize toolbar... ->
   Add... and pick "ReaWild - Toggle ... lane". The button lights up while
   its lane is hidden.

11. Not sure where to start? Press "Try the demo" in the window. It opens a
   small project with five real bird calls, set up the recommended way.
   Two more demos are in the "Demo" folder next to this file, including
   one set up wrong on purpose to show the common mistakes.


Updating to a later version
---------------------------

Each version comes in its own folder, and the script inside carries the
version in its name. This one is:

   ReaWild v0.20.2.lua

That's deliberate. REAPER names an action after the file it was loaded
from, so your Actions list shows that name too -- which means you can
always see which version you are actually running, and an old one can
never quietly shadow a new one.

When a new one arrives:

1. Unzip it next to this folder -- NOT inside it, and don't delete this one
   yet (see step 3).
2. In REAPER: Actions -> Show action list -> New action... -> Load
   ReaScript..., and pick the new "ReaWild vNN.lua". It appears in
   the list as its own entry, alongside this one. Run that.
3. First time you run it, it finds the BirdNET already installed by the
   older version and uses it by itself -- nothing is downloaded again. The
   window says which one at the top. From then on, leave the older folder
   where it is, because the BirdNET inside it is the one being used.
4. Once you're happy, you can remove the old entry from the Actions list
   (select it, then Delete). Keep the old folder, though -- BirdNET lives
   in it.

If you'd rather start clean, just delete the old folder too and let the new
version install its own BirdNET from scratch.

Something wrong, or an idea?
----------------------------

Press "Send feedback" at the bottom of the window. Choose "Something went
wrong" or "An idea for something better", type a line in your own words, and
press "Open email".

Your normal email app opens with everything already filled in -- the version,
the paths, the settings and the last lines of the log. Add anything else you
want and press send. Nothing leaves your machine until you do.

A copy is also saved next to the script as "reabird-feedback-<date>.txt", so
you can attach it or send it another way if you prefer.
